Software User's Guide Version 3.3

The Boot CONFIG Process

This chapter describes the Boot CONFIG process. This chapter includes the following sections:

• "What is Boot CONFIG?"
• "How the BOOTP Forwarding Process Works"
• "Using the Trivial File Transfer Protocol (TFTP)"
• "Validating the Configuration Load"
• "Loading an Image at a Specific Time"
• "Configuring Dumping"

What is Boot CONFIG?

Router nonvolatile configuration database memory contains the data that controls the router boot and dump capabilities. The Boot CONFIG commands allow you to modify this data.

Using Boot CONFIG commands, you can:

• Add, modify, or remove entries from the boot and dump configuration database.

• Disable or enable network memory dumping and assign a unique name to the dump files.

• Use the TFTP protocol to transfer (using the TFTP command or copy command) configuration information between router memory and remote hosts.

• View the current boot and dump configuration database.

• Store file images to the Integrated Boot Device (IBD).

• Store the current image to the IBD.

• Leave the Boot CONFIG command environment and return to the CONFIG process.

• List the contents of the IBD.

• Delete files from the IBD.

• Copy files to and from the local router memory and another local router memory or host file system.

• Save any changes you have made to system and protocol parameters.

Changes made to system and protocol parameters through Boot CONFIG take effect when you restart the router or when you reload the router software.

Configuring Booting

Boot files are the same as load image files. A boot file contains the software load for the router and resides on a host server, or an IBD. The host server is, for example, any PC, router, or workstation, that is running the IP protocol and TFTP. The boot configuration database can contain an entry for each boot file, configured using the add command. Each entry contains the address of the host server, the next hop router, and the timeout, path, and filenames of the boot files.

You can configure more than one boot file in the boot configuration database by specifying the path and name of each boot file (using the add command described on page "Add"). If you have more than one host server, you can use a different host server to boot the router when another host server cannot be reached over the network.

To configure booting:

1. Add an address record, using the add address command from the Boot config> prompt, that specifies the interface from which you want it to boot.

2. Add the boot record, using the add boot-entry command from the Boot config> prompt, specifying the host address, next hop router (if necessary), and the path and filename of the host.

Using a Device as a Boot Server

A device can also function as a boot server. Devices that do not have an IBD can obtain their load files or boot files from a router that has an IBD. Use the add boot-entry command to designate the location of the router with the boot file. Make sure that you include the entire path name of the load file with this command. On a router with the load in IBD, this is IBD/filename.

How the BOOTP Forwarding Process Works

BOOTP (documented in RFC 951) is a bootstrap protocol used by a router or a diskless workstation to learn its IP address, the location of its boot file, and the boot server name. A device can act as a BOOTP client or as a BOOTP relay agent for another device. The following sections describe these two processes.

A Device as a BOOTP Client

A device acts as a BOOTP Client when it needs to find the location of the boot file and boot server. You can specifically configure the device's boot PROM configuration record so the router can act as a BOOTP Client, or it can become a BOOTP Client if, during booting, it does not contain a valid file name and path to the location of the boot file and server. When either of these two conditions exists, the router broadcasts a UDP packet over one of its LAN interfaces to the BOOTP server that contains the path name of the boot file and server.

The following describes the BOOT client forwarding process:

1. The BOOTP client copies its MAC address (either Ethernet or Token Ring) into a BOOTP packet (UDP packet) and broadcasts it onto the local LAN. BOOTP is running on top of UDP.

2. The BOOTP server receives the request and looks up the client's Ethernet address in its database. If found, it formats a BOOTP reply containing the client's IP address, the location of its boot file, and the boot server name. The reply is then sent back over the LAN to the BOOTP client.

   Note:

   If multiple hops are required before reaching the BOOTP server, a BOOTP relay agent receives the packet. BOOTP relay agent is explained in the next section.

3. When the router receives the BOOTP reply packet, it uses the information it contains to initiate a TFTP request to the boot server.

A Device as a BOOTP Relay Agent

If BOOTP request requires multiple hops before reaching the BOOTP server, the BOOTP relay agent routes the packet via IP to all BOOTP servers that it knows about. If any other router receives this packet while it is being routed via IP, it will examine the packet to determine whether it is a BOOTP packet and route that packet toward the BOOTP servers that it knows about. The following describes the BOOTP relay agent forwarding process:

1. A device acting as the local BOOTP relay agent, receives the BOOTP request packet from the BOOTP client, modifies the checksum, places an IP header on the packet with the relay agent's IP address copied into the body of the BOOTP request, and routes the packet to all BOOTP servers.

2. The BOOTP servers receive the request and look up the client's MAC address in their database. If a server finds the client's address, it formats a BOOTP reply containing the client's IP address, the location of its boot file, and the boot server name. The reply is then sent to the BOOTP relay agent.

3. The BOOTP relay agent receives the reply, makes an entry in its ARP table for the client, and then forwards the reply to the BOOTP client.

4. The client then continues to boot using the information that is contained in the BOOTP reply packet to initiate a TFTP request to the boot server.

Enabling/Disabling BOOTP Forwarding

To enable or disable BOOTP forwarding on the router, enter the following appropriate command at the IP configuration prompt:

  IP Config> enable bootp

  IP Config> disable bootp

When enabling BOOTP, you are prompted for the following values:

• Maximum number of application hops you want the BOOTP request to go.

  This is the maximum number of BOOTP relay agents that can forward the packet. This is not the maximum number of IP hops to the BOOTP server. A typical value for this parameter is 4.

• Number of seconds you want the client to retry before you forward the BOOTP request. This parameter is not commonly used. A typical value for this parameter is 0.

After accepting a BOOTP request, the router forwards the BOOTP request to each BOOTP server. If there are multiple servers configured for BOOTP, the transmitting server replicates the packet.

Configuring a BOOTP Server

The BOOTP server is either an AIX or UNIX host with a bootpd daemon, or a DOS host (running software available from FTP Software). The BOOTP server contains a file (maintained by the network administrator) that lists all the BOOTP clients that this server is responsible for, and their associated IP addresses, boot file locations, and boot server names.

When the BOOTP server receives a BOOTP request, it matches the MAC address of the client with the MAC address in its BOOTP file. If a match occurs, the server constructs a BOOTP reply and adds the client's IP address, along with the location of the Boot server and boot filename. If a match does not occur, the packet is dropped.

To add a BOOTP server to the router's configuration, enter the following command at the IP configuration prompt:

  IP Config> add BOOTP-SERVER [IP address of server]

You can configure multiple servers. In addition, if you know only the network number of the server, or if multiple servers reside on the same network segment, you can configure a broadcast address for the server using the enable directed-broadcast command at the IP config> prompt.

Using the Trivial File Transfer Protocol (TFTP)

TFTP is a file transfer protocol that runs over the Internet UDP protocol. This implementation provides multiple, simultaneous TFTP file transfers between a router's nonvolatile configuration memory, Integrated Boot Device (IBD), and remote hosts.

TFTP allows you to:

• Store a configuration file from a router to a server
• Copy a configuration file from a server to a router
• Copy a configuration or load file to an IBD.

TFTP transfers involve a client node and a server node. The client node generates a TFTP request onto the network. The router acts as a client node by generating TFTP requests from the router console using the Boot Config> process copy command.

Note:

The tftp command and the copy command have the same function but the syntax is different.

The client can transfer a copy of the configuration file stored in configuration memory, or any file stored in the IBD.

The server is any device (for example, a personal computer (PC), router, or workstation) that receives and services the TFTP requests. When the router acts as a server, transfers are transparent to the user. Use the ELS subsystem tftp message log to view the transfer in progress.

Note:

A file server or router is not allowed to copy any file into another router's nonvolatile config memory or IBD. To write to the router, use the copy command at the destination's local Boot config> prompt.

Before using the copy command, note that:

• The device configuration must include the IP protocol and have at least one configured IP address. Also, the router must not be operating in CONFIG-Only mode.

• When a device's configuration memory is empty (i.e., initially installing the device, corrupted SRAM), you must set the following parameters to restore the device's configuration.

  1. Set the device's host name.

  2. Configure IP so that the device can reach each host with the archived configuration. The Protocol Configuration and Monitoring Reference explains the IP configuration commands.

• The source IP address for TFTP transfers is the device ID. This ID, by default, is a configured IP address for one of the device's network interfaces. To change the router ID, use the set router ID command at the IP Config> prompt.

• All TFTP data transfers are 512 bytes long. A data transfer of less than 512 bytes indicates an end to the transfer. A protocol, client, or remote host error generates an error packet which terminates the transfer.

• Download configuration files into the same type of router from which you are uploading the file.

Every TFTP transfer has a client and server UDP port number. When a client node generates an initial request to the server, an unused UDP port number on the client node is randomly selected as the client port. The server port is the UDP port number 69 (decimal). If a TFTP server is running on the server, it listens on UDP port 69. When the server receives a request from the network, a UDP port number currently unused on the server is randomly selected as the host port. The file transfers then occur on these two UDP ports.

Accessing Configuration Files From a Remote Host or Router

To access configuration files from a remote host or router:

1. At the Boot config> prompt, type copy and press Enter.

2. At the source filename [CONFIG]? prompt, specify the remote IP address and the pathname.

   This is the TFTP host or another router with the file in its IBD.

3. At the destination filename [Config]? prompt, press Enter.

   By pressing Enter you are accepting the default filename, CONFIG. For example:

     Boot config>copy
     source filename[CONFIG]?128.185.210.125:loads/configs/vl-28.cfg
     destination filename [CONFIG]?
     COPYing from "128.185.210.125:loads/configs/vl-28.cfg" to
     "CONFIG"
     COPY succeeded
   

Filename Definitions for IBD

Each file or image stored on the IBD must have a unique loadname associated with it. The file name for the IBD can contain the complete path name in addition to the file name.

Example 1: test.cfg

Example 2: /usr/loads/test.ldc

The following example shows how to store a file to the IBD at the Boot config> prompt:

Example: copy 128.185.210.125:/usr/config/test.cfg ibd/test.cfg

The router accepts any printable ASCII character as part of the file name definition, with two exceptions:

• The file name cannot begin with a numeric character
• The file name cannot contain a RETURN or LF (line feed) character.

The character string can accept a space, but it is recommended that you avoid using a space character, as this character is invisible. Another user who tries to enter the file name without the required space receives an error message.

Note:

When using a IBM 2210 as a boot server for other routers, be sure to include the complete path name to the load file with the add boot-entry command on the booting router.

The following table contains the convention for filename extensions.

Table 10. Conventions for File Name Extensions

Type of File	Filename Extension
Configuration	.cfg
Load	.ldc

IBD Considerations When Transferring a File

When transferring a file to the IBD consider the following:

• A full load may not fit into one bank of the IBD.

• Any load that needs more than one bank for storage writes only to empty, numerically adjacent banks. For example, when storing a load too large for bank 2, the load is stored in bank 3, as long as bank 3 is empty.

• If an adjacent bank is unavailable to store a large load, a TFTP Disk Full message appears on the console, the load is not stored, and the IBD remains unchanged. Any portion of the load that was stored in a bank is then removed.

Transferring Large Amounts of Data to Multiple Files

This function is important for situations where the receiving TFTP server has a bug handling the block count wrapping back to zero or having a value of X'8000'. The TFTP protocol requires that a block count be transmitted with every data block. The acknowledgement for that data block carries the block number that was in the data block being acknowledged. The transmitter of the data won't send any more data until it receives an acknowledgement for the last data block sent. Once the receiver of the data sends the acknowledgement it expects to receive a data block with a block count that is one greater than the block count it previously received. This block count is two bytes long.

Some TFTP servers have improperly implemented this as a signed short word (two-byte variable where the high order bit being 1 indicates a negative value) and others as an unsigned long word (four byte variable).

If the amount of data to be transferred is so great that the block count wraps, then depending on how the receiver verifies the block count, it may or may not acknowledge the data. If the receiver uses a signed short, the problem will be experienced when the block count goes from X'7FFFF' to X'8000'. If the receiver uses an unsigned long or short, the problem will be experienced when the block count goes from X'FFFF' to X'0000'. In both cases the block count in the data block will appear to be less than the previously received block count and the receiver gets confused.

The transmitting TFTP on the router will either receive an error packet or time out waiting for the receiver to respond. When this happens, TFTP on the router will realize that the block count had wrapped and will automatically recover by making a write request to the receiver for a new file. The new file name is derived from the original file name. The new file name is derived by overlaying the last two characters of the original file name with two decimal digits. Every time the block count wraps, a new file will be written until all the data has been transferred. Tools like cat can be used at the receiver to concatenate the files.

Specifying the Maximum Number of Blocks to Transfer to a File at the Receiver

A patch variable was added so that you can specify the maximum number of blocks to transfer to a file at the receiver. This allows you to tell the device to automatically do a write request for a new file once the number of blocks specified has been sent. Doing this circumvents the automatic recovery described above, speeding up the transfer by avoiding the 5-minute timeout period.

The only values that may be specified for this patch variable are: X'FFFF' (65535) and X'7FFF' (32767).

This patch variable is useful if you know that the receiving server has problems handling the wrap of the block count.

Validating the Configuration Load

There are two methods for validating an image before it is written into the device's configuration memory:

• In the first method, the device assigns an identifier, called a Magic Number, to each platform type for the image that is archived and the image that is being restored. If the numbers do not match, the transfer is aborted and the console displays the message Bad Magic Number.

• In the second method, the host name for the device that originally archived the image is compared to the host name for the device that is restoring the image. If the host names do not match, the transfer is aborted and the console displays the message:

    COPY error -
    Got hostname "<hostname>" - is this okay (Yes or [NO])? no
  

  This allows you to bring in the configuration from another device even if the hostname does not match. The configuration needs to be correct for your model device.

  When a transfer fails due to a lack of RAM space, the console displays an error message.

Loading an Image at a Specific Time

There may be occasions when you may want to load an image into a device on a specific day and time when you will be unavailable. You can configure the device to perform a timed load using the timedload activate command. Other commands allow you to view a device's scheduled load information or cancel a scheduled load. See "Boot CONFIG Commands" for information on these commands.

Configuring Dumping

An important feature of the 2210 is the ability to dump the contents of system memory and processor's registers to another host during a system reset that results from a software crash, hardware failure, or by pressing the reset button.

To configure dumping, do the following from the Boot config> prompt:

1. Add address.

   This can be the same as the boot address used in configuring booting.

2. Add a dump entry.

   This is the location of the host or server that is going to receive the dump file. You can add a dump entry with the add dump-entry command. The average size of a dump file is 8 MB.

3. Enable dumping.

   Dumping will not work unless you enable it using the enable dumping command. Dumping will remain enabled until you use the disable dumping command to terminate it.

Dump Files

Dump files contain the contents of the system memory and processor registers.

When the device crashes and dumping is enabled, the contents of memory are written to a remote host using TFTP. Each dump entry contains the location of the host server and the path, timeout, and file names for the dump files.

You can configure the device to automatically append a unique character string to the dump file names. This prevents an existing dump file from being overwritten by subsequent dumps. However, unique naming of the dump files can cause the server's disk to become full if there are successive dumps. Unique naming may also be incompatible with the security requirements of some TFTP servers. Some servers require that a file already exist on the server to allow writing the dumps.

Dump files are for diagnostic purposes only. Enable the device's dump and unique-naming capabilities only on the advice of your Customer Service representative.

TFTP Server, Boot and Dump Directories

You must create directories on the destination server to contain the boot and dump files. These directories must reside on a host server and the boot directories must be globally readable and the dump directories globally writable. The boot and dump functions use the TFTP protocol. Your TFTP server may impose additional restrictions.

Installing Software/Code

To download a new load module from a server into the IBD, perform the following steps:

1. Install your load file into a server that is reachable by the device. Make sure the TFTP daemon is running in your server. On the device, issue the following commands at the router console:

2. At the OPCON prompt (*):

   1. Enter status to display the Config process ID (PID).

      * status
      

   2. Enter talk and the Config PID to access the Config> command environment.

      * talk 6
      

3. At the Config> prompt, enter boot. This will access the Boot config> command environment.

   Config> boot
   Boot config>
   

4. At the Boot config> prompt, enter add address to specify an IP address over which the device can boot. This needs to be done only once for each interface you want to be able to use. It should not be done each time you want to get a new load module.

   You will then be prompted for the following information:

   • Interface number. This is the number of the interface over which the router will transfer the file.

   • New address. This is the IP address of this interface.

   • Net mask. This is the network mask for this interface.

   Boot config> add address
   Which interface is this address for [0]?
   New address [0.0.0.0] ?
   Net mask for this interface [255.255.255.0]?
   

   The next steps are needed only if you added a boot address. If your boot address is already configured, skip these steps and go to step 9.

5. Press Ctrl-P to return to the OPCON prompt (*).

6. Enter restart at the OPCON prompt.

7. Enter talk and the Config PID.

8. Enter boot at the Config> prompt to return to the Boot config> command environment.

9. At the Boot config> prompt, enter tftp get. This initiates the file transfer of the load module.

   You will be prompted for the following information:

   • Local filename. For the local filename, enter the filename of the new load in the IBD.

   • Remote host. For the remote host, enter the IP address of the server.

   • Host filename. For the host filename, specify the entire path and filename on the host machine.

   Boot config> tftp get
   Local filename []?  ibd/newloadfile
   Remote host []?
   Host filename []?
   

10. Enter list boot-entries at the Boot config> prompt. This lists the load modules in your IBD.

    Boot config> list boot-entries
    

    Note the entry number of the load module in the IBD that you were using prior to receiving this load module.

    The boot database is where the router goes to determine where to get the load module from. You may have multiple entries in your database. The first entry is usually a load module in the IBD, and the second is usually a load module on a remote host or router.

11. To change the boot database pointer to the module you just loaded, enter change boot at the Boot config> prompt. This is what determines which load module is used the next time you reboot the router.

    Boot config> change boot
    

    You will then be prompted for the entry number of the previous module you were using in IBD. This is the entry number from step 10. The boot entry number will usually be "1".

    Change which entry?: 1
    

12. Enter the filename of the new load. This is the name that you specified at step 9 to store in the IBD. Filenames are case sensitive.

    remote host or IBD load name:
    

13. Enter exit.

    Boot config> exit
    

14. Press Ctrl-P to return to the OPCON prompt (*).

15. Enter restart to make sure the configuration change from the "change boot" command takes effect.

16. Enter reload to load the device with the new load module.

17. Once you are confident with the new load, you can create space in your IBD for future loads by erasing the previous load:
    1. Enter talk 6.
    2. Enter boot.

       Config> boot
       

    3. Enter list ibd to list the content of the banks. Note the number of the banks where the previous load is stored.

       Boot config>list ibd
       

    4. Enter erase and either the previous load name or the bank numbers. For example, to erase from bank 36 to 50, enter:

       Boot config> erase 36-50